#%RAML 1.0 DataType
description: |
    This resource type describes completed and in-progress buildrequests.
    Much of the contextual data for a buildrequest is associated with the buildset that contains this buildrequest.


    Update Methods
    --------------

    All update methods are available as attributes of ``master.data.updates``.

    .. py:class:: buildbot.data.buildrequests.BuildRequest

        .. py:method:: claimBuildRequests(brids, claimed_at=None, _reactor=twisted.internet.reactor)

            :param list(integer) brids: list of buildrequest id to claim
            :param datetime claimed_at: date and time when the buildrequest is claimed
            :param twisted.internet.interfaces.IReactorTime _reactor: reactor used to get current time if ``claimed_at`` is None
            :returns: (boolean) whether claim succeeded or not

            Claim a list of buildrequests

        .. py:method:: unclaimBuildRequests(brids)

            :param list(integer) brids: list of buildrequest id to unclaim

            Unclaim a list of buildrequests

        .. py:method:: completeBuildRequests(brids, results, complete_at=None, _reactor=twisted.internet.reactor)

            :param list(integer) brids: list of buildrequest id to complete
            :param integer results: the results of the buildrequest (see :ref:`Build-Result-Codes`)
            :param datetime complete_at: date and time when the buildrequest is completed
            :param twisted.internet.interfaces.IReactorTime _reactor: reactor used to get current time, if ``complete_at`` is None

            Complete a list of buildrequest with the ``results`` status

properties:
    buildrequestid:
        description: the unique ID of this buildrequest
        type: integer
    builderid:
        description: the id of the builder linked to this buildrequest
        type: integer
    buildsetid:
        description: the id of the buildset that contains this buildrequest
        type: integer
    claimed:
        description: |
            True if this buildrequest has been claimed.
            Note that this is a calculated field (from claimed_at != None).
            Ordering by this field is not optimized by the database layer.
        type: boolean
    claimed_at?:
        description: |
            time at which this build has last been claimed.
            None if this buildrequest has never been claimed or has been unclaimed
        type: date
    claimed_by_masterid?:
        description:  |
            the id of the master that claimed this buildrequest.
            None if this buildrequest has never been claimed or has been unclaimed
        type: integer
    complete:
        description: true if this buildrequest is complete
        type: boolean
    complete_at?:
        description: |
            time at which this buildrequest was completed, or None if it's still running
        type: date
    priority:
        description: the priority of this buildrequest
        type: integer
    properties?:
        description: a dictionary of properties corresponding to buildrequest.
        type: sourcedproperties
    results?:
        description: |
            the results of this buildrequest (see :ref:`Build-Result-Codes`), or None if not complete
        type: integer
    submitted_at:
        description: time at which this buildrequest were submitted
        type: date
    waited_for:
        description: |
            True if the entity that triggered this buildrequest is waiting for it to complete.
            Should be used by an (unimplemented so far) clean shutdown to only start br that are waited_for.
        type: boolean
type: object
